What & why

The repo's import convention (AGENTS.md → Imports) states:

Subpath imports for intra-package refs: every package declares "imports": { "#src/*": "./src/*" } in its package.json. Code writes import { x } from '#src/context.ts'; for cross-directory imports. Same-directory siblings (e.g. plan.test.ts → ./plan.ts) may stay relative.

The @contextbridge/annotation package violated this: it did not declare the #src/* mapping in its package.json and used relative ../ / ../../ paths for every cross-directory intra-package import. Every other backend/library package (cli, context, harness, instrumentation, server, shared, skills, storage, ui) already declares #src/* and complies. This was the single most egregious convention-violation class in the codebase — a clearly documented rule, the highest-frequency mechanical violation (26 import sites), and safely fixable with zero runtime behavior change.

Changes

• packages/annotation/package.json — added "imports": { "#src/*": "./src/*" }, matching every other package.
• Converted all 26 cross-directory relative imports to #src/* across 11 files under packages/annotation/src/:
  • demo/DemoStage.tsx, element/ElementAdapter.ts, element/mermaid/MermaidBlock.tsx, element/mermaid/mermaidAdapter.ts, element/mermaid/mermaidAdapter.test.ts, element/useElementTargets.ts, and the testHelpers/* files.
  • Example: import { App } from '../App.tsx'; → import { App } from '#src/App.tsx';; '../../annotationTypes.ts' → '#src/annotationTypes.ts'.
• Same-directory ./ sibling imports were intentionally left relative, exactly as the convention permits.

The changes are purely a module-resolution rename to identical targets — no logic, control flow, or exported surface changed.

Verification

• bun run --cwd packages/annotation typecheck — passes (confirms #src resolves under moduleResolution: bundler, before and after).
• vite build (annotation) — succeeds, 4730 modules transformed; production single-file bundle produced and grep -c xterm dist/index.html returns 0 (the AGENTS.md invariant that demo-only xterm code never lands in the embedded CLI bundle still holds).
• bun run lint — passes (--max-warnings 0).
• bun run format:check — passes.
• Not run: the annotation vitest browser-mode suite could not execute in this sandbox because Playwright's Chromium binary is unavailable (network-restricted download). The import changes are semantically identical resolutions and go through the same Vite resolver as the passing production build, so behavior is unaffected; a normal CI runner with Chromium will exercise the tests.

Other violation classes noted (out of scope, for future runs)

• Bun-native APIs (.claude/rules/bun-native-apis.md): a few readdirSync-based directory walks in Bun-only code (packages/skills/src/skills.ts, packages/skills/scripts/check.ts, packages/storage/src/db/loadMigrations.macro.ts) could use Bun.Glob. Judgment-heavy; deferred.
• ?? fallbacks vs destructured defaults: high raw count, but the vast majority are legitimate null-coalescing (map lookups, array indexing, regex matches), not options-bag defaults — low signal.
• Website .astro/.mdx relative imports: the website package intentionally does not declare #src/* and follows Astro's own asset/component import conventions; left untouched.